Turnbull China Bikeride/Turnbull China Bikeride - Disc 1.iso/ARGONET/PD/PROGRAMMING/DESKLIBC/SOURCES.ZIP/DeskLib/!DLSources/!Help

Text File | 1995-08-28 | 18KB | 565 lines

    !DLSources - DeskLib Sources application directory
    ••••••••••••••••••••••••••••••••••••••••••••••••••


This application directory contains all DeskLib code-files except for
the final libraries and headers, which are in the !DeskLib application.
It sets the system variable <DeskLib_Sources$Dir> to be the !DLSources
directory.

This directory is *not* needed for writing applications which use
DeskLib - the !DeskLib application contains all the headers and
libraries needed. All source code for DeskLib is contained in this
directory.

The structure of this directory is rather different from previous
DeskLib releases. This is partly because I've attempted to automate the
creation of the various files needed for DeskLib, and because DeskLib is
now available in DLL form, as well as the original statically-linkable
'DeskLib:o.DeskLib'. Code for DLLs has to be compiled with different
flags from normal, so each DeskLib sublibrary now has two or three
subdirectories contining differently-compiled .o files.

In the 'Scripts' subdirectory, there are a few Obey files which can be
used to do various things such as generate makefiles for each
sub-library. See below for a description of what each one does.

Please note that the version of the 'LibFile' program that comes with
Acorn's Desktop C can crash the whole system very nastily if there isn't
enough memory (it trashed my HD's boot block in doing so once). It seems
to grab 1.5Mb if possible, so the scripts which actually call LibFile
have a 'Wimpslot 1500k' to ensure there is enough space for LibFile to
work in. This seems to be enough memory to build DeskLib at least.

All of the scripts are of type 'TaskObey' so run in a taskwindow if
double clicked. This probably slows down compiling, but I prefer to keep
my system multitasking where possible. Everything should work fine if
you settype them to be vanilla Obey files.

The 'Bin' directory contains a few of programs which I use to do various
things sycj as create makefiles in each DeskLib sublibrary directory.

The 'Libraries' directory contains, as before, a separate directory for
each DeskLib sub-library. Each has two or three makefiles which make the
various files. These makefiles are now created automatically using
template makefiles in the 'TemplateMF' directory.



Remaking DeskLib
————————————————

This should be fairly straightforward:

The file '!DLSources.Scripts.Static.MakeAll' will remake those parts of
the static version of DeskLib that are out of date, by running Amu on
each library's makefile.

The file '!DLSources.Scripts.Static.MakeAll2' is more drastic - it
deletes all the .o files, retrims the header files, remakes all the
makefiles from the template makefiles in '!DLSources.TemplateMF', and
then recompiles everything.

The files '!DLSources.Scripts.Static+DLL.MakeAll' and
'!DLSources.Scripts.Static+DLL.MakeAll2' are similar to the above,
except that they also remake the dynamic-linking version of DeskLib.

The file '!DLSources.Scripts.OtherLibs.MakeAll' remakes the libraries
which aren't part of the main DeskLib library - Debug and SmallError.




Dynamically Linked DeskLib sublibraries
———————————————————————————————————————

When making a client for use with DeskLib DLLs, link with
'DeskLib:o.DLLClient' (instead of 'DeskLib:o.DeskLib'). This file
contains the stubs files of all DeskLib sublibraries available as DLLs,
and suitably-compiled .o files from all the other sublibraries (for full
information about making DLL clients, see
'...Docs.DynamLink.SDLS_Apps').

This ensures that, when making a client to use DLL DeskLib, code for
DeskLib functions not available as a DLL is linked in statically.

Only about half of the DeskLib sublibraries have DLL versions. This is
because it is not practical to make a DLL version of (say) WimpSWIs -
for example, just one call to a Wimp SWI would involve loading the
entire 5k WimpSWIs DLL into the RMA. Instead, the call is statically
linked into the client. This is generally true for any DeskLib
sublibrary which consists of many small unrelated functions.

There is also what appears to be a 1.2k overhead when making a DLL, so
very small DeskLib sublibraries (eg Sound) are also not available as
DLLs.



Other
—————

To enable auto-generation of appropriate makefiles for the sublibraries
and auto-generation of the final DeskLib libraries, sub-libraies which
are available as DLLs have a zero-length 'IsDLL' file in their
directory.

Code for use in a DLL has to be compiled with various special cc flags,
so every DeskLib sublibrary which has a DLL version has two different
sets of .o files. These are in '<sublibname>.DLL' and
'<sublibname>.Static'.

In addition, every sublibrary which is not available as a DLL has three
sets of .o files - for static linking, static linking with a DLL client,
and static linking with a DLL.





Fairly complete description of all files in this !DLSources directory
—————————————————————————————————————————————————————————————————————

Here is what is where:


!Boot        Sets the system variable DeskLib_Source$Dir to point to
        this directory. Also sets DeskLib_Run$Path to point to the
        Bin subdirectory, and adds DeskLib_Run: to your
        Run$Path.
        Sets 'DeskLib_Commands:' to point to
        '!DLSources.Scripts.Commands.'.

!Run        Simply runs !Boot.

!Help        This file.

!Sprites    The !DLSources sprite - a green version of the normal
        DeskLib sprite.

Bin.        Some general utilities used by some of the scripts described
        below. They might be useful for non-DeskLib things as well.
        This 'Bin' directory is added to Run$Path.

    Every        Runs a command on every file/dir in a directory.
            Just type 'Every' to get help.

    CTrim        Strips comments from a C source file. Only
            overwrites the destination file if the new file
            differs. This is to allow modification of
            comments in h_doc headers, without forcing
            recompilation of hundreds of C files.

    TrimCRs        Removes all CR characters from a file.

    Makatic        Used to make makefiles suitable for a particular
            project directory, using a template makefile.

    IfExist        Runs a command only of the specified file/dir
            exists.

    IfNotExist    Runs a command only of the specified file/dir
            doesn't exist.



Libraries.    Every DeskLib sub-library's source, makefiles etc.

    <Lib-name>.

        Every sublibrary has the following
        source-directories:

        c.    C source
        s.    Assembler source
        h.    Internal headers

        Every library also has the following directory:

        Static.        All files for the conventional version
                of this sublibrary.

            Makefile    The makefile

            Lib        One-chr long file which has the
                    date-stamp of the last creation
                    date of this library.

            o.        The .o files.


        DeskLib sublibraries which are not available as a DLLs
        ——————————————————————————————————————————————————————

        As well as the normal static .o files described above,
        there are two extra sets of .o files, in 'DLLClient'
        and 'DLL':

    <Lib-name>.DLLClient.    All files needed when statically
                linking this sublibrary with a
                client application.
                The .o files are compiled with
                _DeskLib_SDLS_CLIENT predefined.

            MkClientOs    This makefile compiles the
                    source with _DeskLib_SDLS_CLIENT
                    predefined.

            o.        The .o files.


        DLL.        All files needed when statically
                linking this sublibrary with a
                DLL.

            MkOs        Compiles the source with cc -zM
                    etc.

            o.        The object files.



        DeskLib sublibraries which are available as a DLLs
        ——————————————————————————————————————————————————

        As well as the normal static .o files described above,
        there is one extra set of .o files in 'DLL' plus a few
        extra files which are needed to make the DLL version.

    <Lib-name>.DLL.        Everything for making this
                sublibrary into a DLL.

            o.    Object code compiled
                with special flags
                for use in SDLS DLLs:
                -zM
                -D_DLL
                etc.

            MakeStubsOs
                This makefile compiles
                all the .c files and
                makes the DLL Stubs file.

            PlainStubs
                Plain stubs file as created
                using SDLS's 'cdll' tool.

            OSObj    An extra .o file which
                imports symbols from every
                Stubs file that this sublibrary
                references. This is an assembled
                version of 'OtherStubs'
                described below.

            Stubs    The Stubs file for this
                sublibrary. This is simply the
                'PlainStubs' and 'OSObj' object
                files partially linked together.

            MakeDLL    This makefile makes the DLL
                by linking all the .o
                files with 'Header',
                DeskLib:o.DLLDLL and a
                few .o files which come
                with the SDLS.

            Header    Intermediate file used
                to make the 'DLL' file.


        These are a few extra files in DLL library directories.

        OtherStubs
            Small assembler source. Only
            used when making DLL Stubs
            files. See
            '!DLSources.Docs.RndDLLInfo' for
            more information about this.


        DLLDef    (Libraries.DLL.*. only)

            Text file which specifies what functions the DLL
            provides. If this is not present, the DLL
            makefile will use cdll to make a default one based
            on what .o files are present, but this will need
            modifying by hand.

            NB the DLLDef file is not in the 'DLL' directory
            because it is effectively a source file - it is
            tweaked by hand after generation by cdll. Hence
            keeping it outside the 'DLL' directory means that
            one can delete all the 'DLL' directories to save on
            disc space but still be able to restore all DLL
            information easily.

        IsDLL    Zero-length file which is present only in
            sub-libraries which are available as DLLs.
            The presence/absence of this file is checked by
            the various DeskLib scripts so that different
            things are done to libraries which can/can't be
            made into DLLs.



OtherLibs.    A few libraries which aren't part of the main DeskLib
        library-files.

    Debugs.        Some alternative debugging libraries

        Makefile    This puts the different debugging
                libraries into <DeskLib$Dir>.o.Debug.
        o.
        c.

    SmallError.    An alternative to the standard Error library.
            It sends error messages to stderr. Useful for
            using Error_Report* in command line programs.
            The generated library is
            '<DeskLib>.Other.SmError'.


TemplateMF.    Contains template makefiles for making static and
        dynamically-linked versions of the DeskLib sublibraries.
        These makefiles just need the macro $(ObjectFiles) to
        be set to be a space-separated list of .o files, and
        $(LibName) to be set to the name of the library, and
        they will compile/assemble etc as necessary.
        The 'Makatic' command is used to generate real usable
        makefiles from these templates in each of the
        sub-library directories.

    Static        Produces standard .o files

    MakeDLL        Links .o files with the DeskLib:o.DLLDLL library
            to make the finished DLL.

    MkStubsOs    Compiles all .c/s files with flags suitable for
            making into a DLL.
            Uses cdll to make a stubs file.
            Uses cdll to generate a default Defs file if
            none is present.

    MkOs        Compiles all .c/s files with flags suitable for
            linking statically with a DLL.  Used for libraries
            which aren't available as a DLL.

    MkClientOs    Makes .o files suitable for static linking with
            a client application. Used for libraries which
            aren't available as a DLL.


ObjLists.    Various text files which contain lists of .o
        files for use with LibFile to make the finished DeskLib
        libraries.

        Note that these lists are generated automatically by
        scripts before LibFile is called, so that they are
        always up to date. They take a few minutes to generate
        at the moment, because they use a rather clumsy system
        of calling Obey file CLI commands.

    DLLDLL        List of all Stubs files, and all .o files
            from non-DLL sublibraries compiled for use in
            DLLs.
            ie.
            <DeskLib_Sources$Dir>.Libraries.DLL.*.DLL.Stubs
            <DeskLib_Sources$Dir>.Libraries.Static.*.DLL.o.*

    Static        List of all .o files compiled conventionally for
            use in the standard DeskLib library.
            ie.
            <DeskLib_Sources$Dir>.Libraries.Static.*.Static.o.*
            <DeskLib_Sources$Dir>.Libraries.DLL.*.Static.o.*

    DLLClient    List of all Stubs files, and all .o files
            from non-DLL sublibraries compiled for use in
            clients.
            ie.
            <DeskLib_Sources$Dir>.Libraries.DLL.*.DLL.Stubs
            <DeskLib_Sources$Dir>.Libraries.Static.*.Static.o.*


Scripts.    Some TaskObey files which do various things such as
        generate makefiles, run makefiles etc. NB a TaskObey
        file is the same as a normal obey file, except it runs
        in a taskwindow when double-clicked.


    Static+DLL.    These scripts make both the static and DLL parts of
            DeskLib


        MakeAll        Does everything needed to make
                the three DeskLib library files.

        MakeLibs    Does all the LibFile-ing needed to completely
                remake DeskLib. Useful if a library is changed
                - just run the library's makefiles and then
                run this script. This saves running every
                makefile as done by MakeAll.

        CleanC        Removes all C .o files.

        Clean        Removes all .o files.

        MakeMFs        Remakes every makefile in the sublibraries.

        MakeAll2    This *completely* remakes DeskLib - new makefiles,
                trims the DeskLib headers, deletes all .o files
                and recompiles etc.


    Commands.    Some general DeskLib-specific commands.
            These are accessed with (for eg.)
            DeskLib_Commands:EachStatic ...

        EachStatic    'EachStatic <command>' runs <command> on
                every static-only DeskLib sublibrary. Any
                occurrence of '%0' is replaced by the
                complete dirname of the sublibrary, while
                '%1' is replaced by the leafname of the
                sublibrary (ie the sublibrary name).
                This uses 'Every' and 'IfNotExist'.

        EachDLL        As above, except <command> is run on each
                DLL-sublibrary.

        EachLib        As above, except <command> is run on all
                DeskLib's sublibraries, both static and DLL.

        EachUser    As above, except <command> is run on all
                the libraries in '!DLUser'.

        Append        'Append <file> <text>' appends '|<text>'
                to <file>






    Static.        All the scripts to do with making the static DeskLib
            DeskLib:o.DeskLib

        MakeAll        This makes the entire static version of
                DeskLib, 'DeskLib:o.DeskLib'.
                It first runs RunStaMFs, then runs MakeLib.

        MakeOList    Makes ObjLists.Static, a list of all .o
                files compiled for the static version of
                DeskLib

        MakeStaMFs    Makes a makefile in each sublibrary
                directory. The makefile makes each
                .c/s file into a .o suitable for the
                static version of DeskLib.

        RunStaMFs    This runs AMU on each makefile created by
                the above MakeStaMFs.

        MakeLib        Runs MkOList to generate the file
                ObjLists.Static, and then uses LibFile to
                merge all .o files into DeskLib:o.DeskLib.

        CleanC        Deletes every .Static.o.* file which was
                made from a .c file.

        Clean        Deletes every .Static.o.* file.

        MakeAll2    This *completely* remakes the static DeskLib
                library - new makefiles, trims the headers,
                deletes all static .o files and recompiles
                them, and then calls LibFiles to make
                DeskLib:o.DeskLib .
                Note that the DLL DeskLib is not updated.

        CleanMake    Deletes all static .o files and recompiles,
                and then remakes DeskLib:o.DeskLib .


    DLL.        All the scripts to do with making the DLL DeskLib.

        CleanDLLC    Deletes all .o files that came from .c files.

        CleanDLLOb    Deletes all non .o object files - Stubs,
                PlainStubs, OSObj and Header. I used this when
                a new version of the SDLS came out.

        CopySObjs    Copies every .o file that came from
                assembling a .s file in the 'Static'
                subdirectory, into the .o directory of
                the 'DLL' subdirectory.

        MakeAll        This makes the two DLL-DeskLibs
                DeskLib:o.DLLDLL and DeskLib:o.DLLClient
                It first runs RunSubsOs, then MakeDLibs,
                then RunDLL, then MoveDLLs.

        MkDCList    Generates the 'ObjLists.DLLClient' file
                - all DLL Stubs files plus all .o files
                from non-DLL sublibraries compiled for
                linking with *clients*.

        MkDDList    Generates the 'ObjLists.DLLDLL' file -
                all DLL Stubs files plus all .o files
                from non-DLL sublibraries compiled for
                linking with *DLLs*.

        MakeDLibs    Makes the two libraries needed for DLL client
                and the actual SDLS libraries.


        MakeTree    Makes all the subdirs and makefiles for a DLL
                sublibrary.


        -- Scripts for making makefiles --

        MakeDLL        Uses Makatic to generate a makesfile in each
                DLL sublibrary directory which makes the DLL.
                Each makefile is based on 'TemplateMF.MakeDLL'

        MakeStbsOs    Uses Makatic to make a makefile in each DLL
                sublibrary directory which makes all .o files
                for that library and also makes the Stubs
                file for that sublibrary. Each makefile is based
                on TemplateMF.MakeStubsOs
                Also makes the MakeOs makefile in each non-DLL
                sublibrary, whch makes all .o files suitable for
                linking with a DLL.

        MkClientOs    Uses Makatic to make a makefile in each
                static-sublibrary. This makefile will make .o
                files suitable for static linking with client
                applications.

        MakeAllMFs    Calls all three of the above files.


        -- Scripts for running makefiles --

        RunClientO    Runs each <libname>.DLLClient.MkClientOs makefile.

        RunDLL        Runs the 'MakeDLL' makefiles in each DLL-library.

        RunStubOs    Runs each of the MakeDLL makefiles.


    OtherLibs    Scripts for making the extra libraries that aren't
            included in the main 'DeskLib:o.DeskLib' library
            (eg Debug and SmallError).

        MakeAll    Runs amu on the makefile within each directory in
            '!DLSources.OtherLibs'.

        Clean    Deletes all .o files within
            '!DLSources.Scripts.OtherLibs'.





- Julian Smith